Developer Documentation

QuickTime 4 API Documentation

QuickTime 4 Reference

| Previous | Chapter Contents | Chapter Top | Next |

Obtaining a Graphics Importer Instance

GetGraphicsImporterForFile
GetGraphicsImporterForFileWithFlags

Locates and opens a graphics importer component that can be used to draw the specified file.

pascal OSErr GetGraphicsImporterForFile (
                     const FSSpec *theFile,
                     ComponentInstance *gi);
In this version of the call, no flags are passed.
 
pascal OSErr GetGraphicsImporterForFileWithFlags (
                     const FSSpec *theFile,
                     ComponentInstance *gi,
                     long flags);
theFile
Specifies the file to be drawn using a graphics importer component.
gi
On return, contains a pointer to the ComponentInstance of the graphics importer. If no graphics importer can be found for the specified file, the gi will be set to nil .
flags
Controls the graphics importer search process. The following flag is available:
kDontUseValidateToFindGraphicsImporter
If a graphics importer cannot be found using the file's type or file extension, give up immediately without using the slower process of asking graphics importers to validate the file.

DISCUSSION

GetGraphicsImporterForFile first tries to locate a graphics importer component for the specified file based on it's file type. If it is unable to locate a graphics importer component based on the Macintosh file type, or the call is made on a non-Macintosh file, GetGraphicsImporterForFile will try to locate a graphics importer component based on the file extension (such as .JPG or .GIF).

If a graphics importer cannot be found using the file's type or extension, GetGraphicsImporterForFile asks each graphics importer to validate the file, until it either finds an importer that can handle the file or exhausts the list of possible importers. This validation attempt can be quite time-consuming. To bypass the validation attempt, call GetGraphicsImporterForFileWithFlags instead.

If GetGraphicsImporterForFile is unable to locate a graphics importer for the file, the returned ComponentInstance is set to nil . If it is able to locate a graphics importer for the file, the returned graphics importer ComponentInstance will already be set up to draw the specified file to the current port.

The caller of GetGraphicsImporterForFile is responsible for closing the returned ComponentInstance using CloseComponent .

GetGraphicsImporterForDataRef
GetGraphicsImporterForDataRefWithFlags

Locates and opens a graphics importer component that can be used to draw the image from specified data reference.

pascal OSErr GetGraphicsImporterForDataRef (
                     Handle dataRef,
                     OSType dataRefType,
                     ComponentInstance *gi);

pascal OSErr GetGraphicsImporterForDataRefWithFlags (
                     Handle dataRef,
                     OSType dataRefType,
                     ComponentInstance *gi,
                     long flags);

dataRef
Specifies the data reference to be drawn using a graphics importer component.
dataRefType
Specifies the type of data reference pointed to by the dataRef parameter. For alias-based data references, the dataRef handle contains an AliasRecord , and dataRefType is equal to rAliasType .
gi
On return, contains a pointer to the ComponentInstance of the graphics importer. If no graphics importer can be found, gi will be set to nil .
flags
Controls the graphics importer search process. The following flag is available:
kDontUseValidateToFindGraphicsImporter
If a graphics importer cannot be found using the file's type, file extension, or MIME type, give up immediately without attempting the slower process of asking each graphics importer to validate the file.

DISCUSSION

GetGraphicsImporterForDataRef tries to locate a graphics importer component for the specified data reference by checking the file extension (such as .GIF or .JPG), the Macintosh file type, and the MIME type of the file. The file extension is retrieved from the data reference by use of the DataHGetFileName call to the data handler associated with the data reference.

If a graphics importer cannot be found using the file's type, file extension, or MIME type, GetGraphicsImporterForDataRef asks each graphics importer to validate the file, until it either finds an importer that can handle the file or exhausts the list of possible importers. This validation attempt can be quite time-consuming. To bypass the validation attempt, call GetGraphicsImporterForDataRefWithFlags instead.

If GetGraphicsImporterForDataRef is unable to locate a graphics importer for the file, the returned ComponentInstance is set to nil . If it is able to locate a graphics importer for the data reference, the returned graphics importer ComponentInstance will already be set up to draw from the specified data reference to the current port.

The caller of GetGraphicsImporterForDataRef is responsible for closing the returned ComponentInstance using CloseComponent .

You must call CloseComponent when you are finished with the importer.

© 1999 Apple Computer, Inc.

| Previous | Chapter Contents | Chapter Top | Next |